---
title: ReportBase
summary: API reference for ReportBase.
status: draft
owner: SAIF Documentation
last_reviewed: 2026-08-21
library: SAIF.Services.Printing
reference_type: embedded
---

# ReportBase

`ReportBase` is the abstract implementation of `IReport` and the single content-orchestration point for the
`Reporting` framework: it drives the report lifecycle (build → render → print/distribute/save), resolves the
default printer and security platform for rendering, and captures non-throwing failures into `Errors`. It is
`MustInherit`; concrete reports in consuming libraries subclass it and override `Create` to build their
xPression data document. No concrete subclass exists in this repository's built projects — the only sample is
in a test project excluded from the solution.*

## Purpose
- Implement the render/print/distribute/save orchestration defined by `IReport`, delegating actual rendering
  and transport to an internally held `clsPrint` instance
- Cache a rendered report so repeated calls avoid another xPression round trip unless the caller requests an
  overwrite ([BR-PRT-007](../../business-rules.md#br-prt-007-render-result-caching))
- Enforce that render/distribute only proceed once the report's data document and package are both present
  ([BR-PRT-008](../../business-rules.md#br-prt-008-render-and-distribute-preconditions))
- Select the rendering printer from the caller's security principal, choosing the Web or Windows platform based
  on `EnvironmentServiceBase.IsWeb` ([BR-PRT-009](../../business-rules.md#br-prt-009-default-printer-and-security-platform-selection))
- Record render/distribute exceptions as `ErrorDetail` entries instead of throwing
  ([BR-PRT-010](../../business-rules.md#br-prt-010-non-throwing-render-and-distribute-failures))

## Context
- Namespace: `SAIF.Services.Printing.Reporting`
- Assembly/package: `SAIF.Services.Printing` (embedded library, project reference)

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| `XpressoEnvironments` | `Public Enum XpressoEnvironments {Production, Test, NotSpecified}` (nested) | Declares xPression environment tokens |
| `XpressoEnvironment` | `Public Property As XpressoEnvironments` | Settable but not read by any logic in this library — has no observed effect on rendering** |
| `New()` | `Public Sub New()` | Resolves the ambient `AppGlobal.EnvironmentService` and delegates to the parameterised constructor |
| `New(envSvc)` | `Public Sub New(envSvc As EnvironmentServiceBase)` | Initialises the report with the supplied environment service |
| `Errors` | `ReadOnly Property Errors As List(Of ErrorDetail)` (`IReport` implementation) | Accumulated render/distribute failures ([BR-PRT-010](../../business-rules.md#br-prt-010-non-throwing-render-and-distribute-failures)) |
| `xPrint` | `ReadOnly Property xPrint As clsPrint` (`IReport` implementation) | The `clsPrint` instance this report renders/prints/distributes through; constructed with `clsPrint`'s parameterless constructor, so the report's own injected environment service is not propagated to it* |
| `DestinationFileName` | `Property DestinationFileName As String` (`IReport` implementation) | File path used by `Save` |
| `OutputProfile` | `Property OutputProfile As String` (`IReport` implementation) | Output profile applied on render; defaulted via `SetDefaultProfile`/`SetDraftProfile` |
| `ReportPackage` | `Property ReportPackage As String` (`IReport` implementation) | xPression package name required for render/distribute ([BR-PRT-008](../../business-rules.md#br-prt-008-render-and-distribute-preconditions)) |
| `ReportFile` | `Property ReportFile As Byte()` (`IReport` implementation) | Cached rendered bytes populated by `Render` |
| `ReportXml` | `Property ReportXml As XDesignXDocument` (`IReport` implementation) | The data document produced by the subclass's `Create` override |
| `Create` | `Overridable Function Create(overwrite As Boolean) As XDesignXDocument` | Clears `Errors` and returns the subclass-built data document; the only member concrete report subclasses are expected to override |
| `Render` | `Function Render(overwrite As Boolean) As Boolean` | Skips re-rendering when a report file exists and `overwrite` is `False` ([BR-PRT-007](../../business-rules.md#br-prt-007-render-result-caching)); otherwise calls `Create`, checks the data-document/package precondition ([BR-PRT-008](../../business-rules.md#br-prt-008-render-and-distribute-preconditions)), resolves the default printer and security platform ([BR-PRT-009](../../business-rules.md#br-prt-009-default-printer-and-security-platform-selection)), serializes with `ToXpression`, and calls `xPrint.previewDocument`; failures populate `Errors` and return `False` ([BR-PRT-010](../../business-rules.md#br-prt-010-non-throwing-render-and-distribute-failures)) |
| `Print` | `Function Print(printer As String, overwrite As Boolean) As Boolean` | Renders when needed (OP-06 caching), sets `xPrint.Printer` to the caller-supplied printer, and calls `xPrint.printPDF` |
| `Distribute` | `Function Distribute(overwrite As Boolean) As Boolean` | Calls `Create` when needed, checks the precondition ([BR-PRT-008](../../business-rules.md#br-prt-008-render-and-distribute-preconditions)), and calls `xPrint.distributeDocument` with the raw `XDocument.ToString` output rather than `ToXpression`, unlike `Render`*; failures populate `Errors` and return `False` |
| `Save` | `Function Save(overwrite As Boolean) As Boolean` | Renders when the destination file does not exist or `overwrite` is set and a destination name is present, writes `ReportFile` to a new `FileStream`, and returns whether the destination file now exists ([BR-PRT-014](../../business-rules.md#br-prt-014-destination-file-overwrite-protection)) |
| `SetDefaultProfile` | `Sub SetDefaultProfile()` | Sets `OutputProfile` to the private constant `PDF` ([BR-PRT-015](../../business-rules.md#br-prt-015-draft-versus-final-output-profile)) |
| `SetDraftProfile` | `Sub SetDraftProfile()` | Sets `OutputProfile` to the private constant `PDF_Draft_Watermark` ([BR-PRT-015](../../business-rules.md#br-prt-015-draft-versus-final-output-profile)) |

## Behavioral notes
- `Render` chooses `clsSecurityPrincipal.Platform.Web` when `EnvironmentServiceBase.IsWeb` is true and
  `.Windows` otherwise, then takes `GetDefaultPrinter()` from that principal as the printer used for the
  underlying `clsPrint` call ([BR-PRT-009](../../business-rules.md#br-prt-009-default-printer-and-security-platform-selection)).
- `Distribute` checks `m_reportFile` to decide whether to re-build, but calls `Create` (not `Render`) — so a
  distribute-only flow never populates `ReportFile` via the render path.*
- `xPrint` is constructed with `clsPrint`'s parameterless constructor regardless of which environment service
  `ReportBase` itself received, so the two could resolve different environment services within one report
  lifecycle.*

## Constraints and usage notes
- Subclasses should override only `Create`; the remaining lifecycle members are not designed to be overridden.
- Callers that need render results without the "already rendered" cache skip must pass `overwrite = True`.

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

## Sources
- SAIF.Services.Printing/Reporting/ReportBase.vb